What was changed

.editorconfig

• Added support for tabs in Makefiles, facilitating consistent code formatting across various editors because Makefiles are strict about tab usage.

yamllint

• Introduced YAML linting capabilities with the new Makefile command make lint-yaml, utilizing the cytopia/yamllint:latest Docker image.
• Applied YAML linting to all .yml and .yaml files to ensure they adhere to our coding standards.

actionlint

• Makefile now has support for linting github actions using make lint-actions command which uses rhysd/actionlint:latest docker image.
• Applied GitHub Actions linting on the entire .github directory to maintain the integrity and functionality of our GitHub Actions workflows.

.github/workflows/build-release.yml

• Created a new workflow that builds, signs, and uploads signed PHAR to the current GitHub release.

.github/workflows/lint-php-files.yml

• Renamed from cs-fixser.yml to lint-php-files.yml to standardize naming conventions across our actions, focusing on the type of action performed (e.g., lint, check, build, create).
• Standardized Composer dependency installation using wayofdev/gh-actions, ensuring consistency and reliability in our dependency management.
• Updated action versions to use specific versions (e.g., shivammathur/setup-php@2.30.4) instead of major version tags to ensure stability and predictability in our CI environment. Pinning to specific versions prevents unexpected changes from impacting our workflows negatively.
• Removed unnecessary fetch-depth: 1 from actions/checkout as it is the default value, simplifying the configuration without altering functionality.
• Deprecated set-output commands have been removed in line with GitHub's best practices to avoid deprecated operations as detailed here.
• Switched to using composer cs:fix for the PHP coding standard fixes instead of the manual full path ./vendor/bin command, which aligns with our standardization efforts and simplifies the command structure.
• Changed the on section to use paths: instead of paths-ignore. This adjustment makes it easier to define the action to run only on PHP files, simplifying maintenance and reducing the risk of unintentionally ignoring important changes.

.github/workflows/static-analysis.yml

• Renamed from psalm.yml to static-analysis.yml to standardize naming conventions across our actions, as this workflow may also perform PHPStan analysis in the future.
• Standardized Composer dependency installation and caching
• Updated action versions to use specific versions to maintain stability and predictability in our CI environment by avoiding unexpected changes.
• Removed unnecessary fetch-depth: 1
• Deprecated set-output commands have been removed
• Switched to using composer psalm:ci for Psalm static analysis instead of the manual full path ./vendor/bin command. This aligns with our standardization efforts and simplifies the command structure. The composer psalm:ci command is specifically designed for CI environments, with flags such as:
  • --output-format=github to optimize output for GitHub Actions
  • --threads=4 to improve performance by parallel processing
• Changed the on section to use paths:

.github/workflows/security.yml

• Removed paths-ignore: to ensure that security checks are run more frequently. Previously, checks were skipped for almost all files, meaning critical files like composer.lock or composer.json could change and not trigger a security check until much later, potentially allowing vulnerabilities to go undetected for an extended period. As vulnerabilities can be identified in dependencies at any time, it's crucial to run security checks on every change to catch issues as soon as they are introduced.
• Enhanced Security Checks: Now, security checks are performed using both composer audit --ansi and composer require --dev roave/security-advisories:dev-latest.
• Standardized Composer dependency installation and caching
• Updated action versions to use specific versions
• Removed unnecessary fetch-depth: 1
• Deprecated set-output commands have been removed
• ⚠️ Suggestion for Scheduled Scans: To complement the trigger on changes, it is advisable to also schedule regular security checks. This can be achieved by adding a scheduled trigger to the GitHub Actions workflow, ensuring that the project is routinely scanned for vulnerabilities, even during periods of lower development activity.
  • Example of Scheduled Trigger:

    on:
      push:
        branches:
          - master
      pull_request:
        branches:
          - master
      schedule:
        # This schedule runs the security checks every Monday at 01:00 UTC.
        - cron: '0 1 * * 1'

.github/workflows/testing.yml

• Applied make lint-yaml
• Future Refactoring: This workflow will be refactored in a future pull request

.gitignore

• Updated to Track composer.lock: Removed composer.lock from the .gitignore file. This change allows us to cache dependencies in GitHub Actions, leveraging consistent environments across builds and reducing build times.

composer.json

• Added platform Configuration: Included the platform field in the composer.json to ensure that dependencies are installed against a specific PHP version. This resolves issues encountered in GitHub Actions where the composer.lock file generated for one PHP version conflicts with another PHP version used during CI.
• Introduced scripts Section: Added a scripts section similar to how Node.js repositories use package.json. This standardizes how we run commands within the project, making our build process more consistent and maintainable.

‼️ Post-review Steps

Please follow these instructions to generate and add GPG keys for PHAR signing.

📜 GPG Guide

This pull request introduces necessary changes and configurations to integrate GPG keys into our GitHub Actions workflow for securely signing PHAR archives. As our project is open-source, ensuring the authenticity of our releases via GPG signatures is crucial to protect our users from malicious tampering and to maintain the integrity of our codebase. The following guide is split into three parts: actions to be performed on the local PC, settings adjustments in the GitHub UI, and updates needed within our GitHub Actions workflow.

💻 Part 1: On Local PC

Perform these steps on your local machine to generate and prepare your GPG keys for integration with the repository.

Step 1: Generate GPG Keys

Open a terminal and run the following command to create a new GPG key pair:

gpg --full-generate-key

Follow the prompts to configure your key (choose RSA, 4096 bits, and a 2-year expiration).

• Please select what kind of key you want: (1) RSA and RSA
• What keysize do you want?: 4096
• Key is valid for?: 2y
• Is this correct?:: y
• Real name: Andrij Orlenko
• Email address:: the@wayof.dev
• Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?: O

After you have finished with prompt, create passphrase for this GPG key:

Final output:

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: directory '/Users/xxx/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/Users/xxx/.gnupg/openpgp-revocs.d/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.rev'
public and secret key created and signed.

pub   rsa4096 2024-05-12 [SC] [expires: 2026-05-12]
      XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uid                      Andrij Orlenko <the@wayof.dev>
sub   rsa4096 2024-05-12 [E] [expires: 2026-05-12]

Step 2: Export GPG Keys

Export your generated public and private keys using:

gpg --armor --export the@wayof.dev > ./public-key.asc
gpg --armor --export-secret-keys the@wayof.dev > ./private-key.asc

Second GPG command will require you to enter passphrase from Step 1: Generate GPG Keys:

Step 3: Encrypt the Private Key

Encrypt your private key with a strong passphrase, as it will be kept encrypted in public buggregator/trap repository:

gpg --symmetric --cipher-algo AES256 --output keys.asc.gpg private-key.asc

Enter passphrase:

Step 4: Copy encrypted key into repository:

cd ./buggregator-trap
mkdir ./phar
cp ../keys.asc.gpg ./phar/keys.asc.gpg

Step 5: Commit and push encrypted key:

git add phar/keys.asc.gpg
git commit -m "ci: add gpg encrypted private key for PHAR signing"
git push

🪄 Part 2: In GitHub UI

Adjust https://github.com/buggregator/trap repository settings

Step 1: Add Secrets

Go to your repository on GitHub, select Settings > Secrets > Actions, and add the following secrets:

• GPG_DECRYPT_PASSPHRASE: Passphrase used to encrypt keys.asc.gpg, from Step 3: Encrypt the Private Key
• GPG_LOCAL_USER: Email or user ID associated with your GPG key.
• GPG_KEY_PASSPHRASE: Your GPG key’s passphrase, if applicable, from Step 1: Generate GPG Keys

⚠️ Security Considerations

Given the sensitive nature of the operations performed within this repository, particularly those involving GPG keys for signing, it is crucial to adopt stringent security measures to safeguard the integrity and confidentiality of our cryptographic assets. Here are the recommended security practices:

1. Internalize Critical Dependencies

• Action: Fork wayofdev/gh-actions into the buggregator GitHub namespace.
• Rationale: This minimizes the risk of exposing GPG passphrases due to dependency vulnerabilities or malicious changes. By maintaining our own fork, we can control updates and audit changes comprehensively before they are integrated into our workflows.

2. Limit Automatic Commit Actions

• Action: Remove the stefanzweifel/git-auto-commit-action@v5.0.1 from our workflows and configure php-cs-fixer to run in diff mode only, not fix mode.
• Rationale: Automated commit actions, while convenient, pose a risk of inadvertently committing sensitive data. Restricting php-cs-fixer to diff mode prevents automatic code modifications that might reveal GPG passphrases or other sensitive information embedded in the code.

3. Secure Asset Uploads

• Action: Use actions/github-script for raw assets upload directly in our workflows instead of relying on third-party actions.
• Rationale: Direct management of upload scripts reduces the risk of exposing sensitive credentials to third-party actions, which may not be audited to the same degree as GitHub-managed actions. This approach allows for greater control and visibility over the transmission of sensitive files.
• Implementation: This change has already been implemented as part of refactor: ci-cd workflows #79, where you can see the specific modifications in the workflow configuration here.

Closes: #20